First Agent

In BindAI, an Agent is the core building block of every AI application. An agent connects a language model with instructions, tools, memory, knowledge, and workflows to perform useful tasks. This guide explains how agents work and how to build your own.

What is an Agent?

An agent is responsible for:

Receiving user input
Building a prompt
Sending the request to a language model
Executing tools when required
Returning the final response

Unlike calling an LLM directly, a BindAI agent can be extended with additional capabilities while keeping the application architecture clean.

Creating an Agent

The simplest agent only requires a provider, model, and instructions.

from bindai_agent import Agent


agent = Agent(
    provider="openai",
    model="gpt-4.1-mini",
    instructions="You are a helpful assistant.",
)

You can immediately interact with it.

result = agent.chat(
    "Explain artificial intelligence in one sentence."
)

print(result.output)

Agent Components

A BindAI agent is composed of several optional building blocks.

Component	Purpose
Provider	Connects to an LLM provider such as OpenAI
Model	Specifies which language model to use
Instructions	Defines the agent’s behavior
Tools	Allows the model to execute Python functions
Memory	Stores previous conversations
Knowledge	Supplies external documents and information
Middleware	Executes logic before and after agent execution
Events	Publishes lifecycle events during execution

You can start with only a provider and model, then add more capabilities as your application grows.

System Instructions

Instructions define the agent’s personality and behavior.

agent = Agent(
    provider="openai",
    model="gpt-4.1-mini",
    instructions="""
You are an experienced Python mentor.
Always explain concepts clearly.
Keep answers concise.
""",
)

Good instructions usually describe:

The agent’s role
Desired writing style
Constraints
Expected output format

Sending Messages

Use the chat() method to send a prompt.

result = agent.chat(
    "What is dependency injection?"
)

The returned value is an AgentResult.

print(result.success)

print(result.output)

Typical output:

True

Dependency injection is a design pattern where dependencies are supplied from the outside instead of being created internally.

Structured Output

Agents can also return structured data. Suppose you have a Pydantic model.

from pydantic import BaseModel

class Person(BaseModel):

    name: str

    age: int

Pass it as the output argument.

result = agent.chat(
    "Generate a fictional person.",
    output=Person,
)

print(result.output)

The response becomes an instance of your model instead of plain text.

Loading Agents from YAML

Agents can be defined without writing Python code. Example configuration:

name: assistant

provider: openai

model: gpt-4.1-mini

instructions: |
  You are a helpful assistant.

Load it.

from pathlib import Path

from bindai_agent import Agent


agent = Agent.from_yaml(
    Path("agent.yaml"),
)

YAML is useful for production projects where prompts and models change frequently.

Streaming Responses

Instead of waiting for the complete answer, responses can be streamed token by token.

for chunk in agent.stream(
    "Explain neural networks."
):
    print(chunk.delta, end="")

Streaming is recommended for chat interfaces and long responses.

Agent Lifecycle

Internally, every execution follows the same pipeline.

Receive user input
Build the prompt
Load memory
Retrieve knowledge (if configured)
Send the request to the language model
Execute requested tools
Generate the final response
Save conversation memory
Return an AgentResult

This lifecycle remains the same regardless of whether the agent uses tools, workflows, or retrieval.

Extending an Agent

Agents become more powerful by adding additional capabilities. For example, register a tool.

agent.tool(
    weather_tool,
)

Attach memory.

agent.use_memory(
    memory,
)

Connect knowledge retrieval.

agent.use_knowledge(
    knowledge,
)

These extensions allow the same agent architecture to support increasingly complex applications.

Getting Started

Core

Tools

Memory

Knowledge

Workflows

Projects

Templates

API Reference

01.4 first agent

First Agent

What is an Agent?

Creating an Agent

Agent Components

System Instructions

Sending Messages

Structured Output

Loading Agents from YAML

Streaming Responses

Agent Lifecycle

Extending an Agent

​First Agent

​What is an Agent?

​Creating an Agent

​Agent Components

​System Instructions

​Sending Messages

​Structured Output

​Loading Agents from YAML

​Streaming Responses

​Agent Lifecycle

​Extending an Agent

First Agent

What is an Agent?

Creating an Agent

Agent Components

System Instructions

Sending Messages

Structured Output

Loading Agents from YAML

Streaming Responses

Agent Lifecycle

Extending an Agent